home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / complib / csysvx.z / csysvx
Text File  |  1998-10-30  |  9KB  |  265 lines
  1.  
  2.  
  3.  
  4. CCCCSSSSYYYYSSSSVVVVXXXX((((3333FFFF))))                                                          CCCCSSSSYYYYSSSSVVVVXXXX((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      CSYSVX - use the diagonal pivoting factorization to compute the solution
  10.      to a complex system of linear equations A * X = B,
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE CSYSVX( FACT, UPLO, N, NRHS, A, LDA, AF, LDAF, IPIV, B, LDB,
  14.                         X, LDX, RCOND, FERR, BERR, WORK, LWORK, RWORK, INFO )
  15.  
  16.          CHARACTER      FACT, UPLO
  17.  
  18.          INTEGER        INFO, LDA, LDAF, LDB, LDX, LWORK, N, NRHS
  19.  
  20.          REAL           RCOND
  21.  
  22.          INTEGER        IPIV( * )
  23.  
  24.          REAL           BERR( * ), FERR( * ), RWORK( * )
  25.  
  26.          COMPLEX        A( LDA, * ), AF( LDAF, * ), B( LDB, * ), WORK( * ), X(
  27.                         LDX, * )
  28.  
  29. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  30.      CSYSVX uses the diagonal pivoting factorization to compute the solution
  31.      to a complex system of linear equations A * X = B, where A is an N-by-N
  32.      symmetric matrix and X and B are N-by-NRHS matrices.
  33.  
  34.      Error bounds on the solution and a condition estimate are also provided.
  35.  
  36.  
  37. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  38.      The following steps are performed:
  39.  
  40.      1. If FACT = 'N', the diagonal pivoting method is used to factor A.
  41.         The form of the factorization is
  42.            A = U * D * U**T,  if UPLO = 'U', or
  43.            A = L * D * L**T,  if UPLO = 'L',
  44.         where U (or L) is a product of permutation and unit upper (lower)
  45.         triangular matrices, and D is symmetric and block diagonal with
  46.         1-by-1 and 2-by-2 diagonal blocks.
  47.  
  48.      2. The factored form of A is used to estimate the condition number
  49.         of the matrix A.  If the reciprocal of the condition number is
  50.         less than machine precision, steps 3 and 4 are skipped.
  51.  
  52.      3. The system of equations is solved for X using the factored form
  53.         of A.
  54.  
  55.      4. Iterative refinement is applied to improve the computed solution
  56.         matrix and calculate error bounds and backward error estimates
  57.         for it.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCSSSSYYYYSSSSVVVVXXXX((((3333FFFF))))                                                          CCCCSSSSYYYYSSSSVVVVXXXX((((3333FFFF))))
  71.  
  72.  
  73.  
  74. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  75.      FACT    (input) CHARACTER*1
  76.              Specifies whether or not the factored form of A has been supplied
  77.              on entry.  = 'F':  On entry, AF and IPIV contain the factored
  78.              form of A.  A, AF and IPIV will not be modified.  = 'N':  The
  79.              matrix A will be copied to AF and factored.
  80.  
  81.      UPLO    (input) CHARACTER*1
  82.              = 'U':  Upper triangle of A is stored;
  83.              = 'L':  Lower triangle of A is stored.
  84.  
  85.      N       (input) INTEGER
  86.              The number of linear equations, i.e., the order of the matrix A.
  87.              N >= 0.
  88.  
  89.      NRHS    (input) INTEGER
  90.              The number of right hand sides, i.e., the number of columns of
  91.              the matrices B and X.  NRHS >= 0.
  92.  
  93.      A       (input) COMPLEX array, dimension (LDA,N)
  94.              The symmetric matrix A.  If UPLO = 'U', the leading N-by-N upper
  95.              triangular part of A contains the upper triangular part of the
  96.              matrix A, and the strictly lower triangular part of A is not
  97.              referenced.  If UPLO = 'L', the leading N-by-N lower triangular
  98.              part of A contains the lower triangular part of the matrix A, and
  99.              the strictly upper triangular part of A is not referenced.
  100.  
  101.      LDA     (input) INTEGER
  102.              The leading dimension of the array A.  LDA >= max(1,N).
  103.  
  104.      AF      (input or output) COMPLEX array, dimension (LDAF,N)
  105.              If FACT = 'F', then AF is an input argument and on entry contains
  106.              the block diagonal matrix D and the multipliers used to obtain
  107.              the factor U or L from the factorization A = U*D*U**T or A =
  108.              L*D*L**T as computed by CSYTRF.
  109.  
  110.              If FACT = 'N', then AF is an output argument and on exit returns
  111.              the block diagonal matrix D and the multipliers used to obtain
  112.              the factor U or L from the factorization A = U*D*U**T or A =
  113.              L*D*L**T.
  114.  
  115.      LDAF    (input) INTEGER
  116.              The leading dimension of the array AF.  LDAF >= max(1,N).
  117.  
  118.      IPIV    (input or output) INTEGER array, dimension (N)
  119.              If FACT = 'F', then IPIV is an input argument and on entry
  120.              contains details of the interchanges and the block structure of
  121.              D, as determined by CSYTRF.  If IPIV(k) > 0, then rows and
  122.              columns k and IPIV(k) were interchanged and D(k,k) is a 1-by-1
  123.              diagonal block.  If UPLO = 'U' and IPIV(k) = IPIV(k-1) < 0, then
  124.              rows and columns k-1 and -IPIV(k) were interchanged and D(k-
  125.              1:k,k-1:k) is a 2-by-2 diagonal block.  If UPLO = 'L' and IPIV(k)
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CCCCSSSSYYYYSSSSVVVVXXXX((((3333FFFF))))                                                          CCCCSSSSYYYYSSSSVVVVXXXX((((3333FFFF))))
  137.  
  138.  
  139.  
  140.              = IPIV(k+1) < 0, then rows and columns k+1 and -IPIV(k) were
  141.              interchanged and D(k:k+1,k:k+1) is a 2-by-2 diagonal block.
  142.  
  143.              If FACT = 'N', then IPIV is an output argument and on exit
  144.              contains details of the interchanges and the block structure of
  145.              D, as determined by CSYTRF.
  146.  
  147.      B       (input) COMPLEX array, dimension (LDB,NRHS)
  148.              The N-by-NRHS right hand side matrix B.
  149.  
  150.      LDB     (input) INTEGER
  151.              The leading dimension of the array B.  LDB >= max(1,N).
  152.  
  153.      X       (output) COMPLEX array, dimension (LDX,NRHS)
  154.              If INFO = 0, the N-by-NRHS solution matrix X.
  155.  
  156.      LDX     (input) INTEGER
  157.              The leading dimension of the array X.  LDX >= max(1,N).
  158.  
  159.      RCOND   (output) REAL
  160.              The estimate of the reciprocal condition number of the matrix A.
  161.              If RCOND is less than the machine precision (in particular, if
  162.              RCOND = 0), the matrix is singular to working precision.  This
  163.              condition is indicated by a return code of INFO > 0, and the
  164.              solution and error bounds are not computed.
  165.  
  166.      FERR    (output) REAL array, dimension (NRHS)
  167.              The estimated forward error bound for each solution vector X(j)
  168.              (the j-th column of the solution matrix X).  If XTRUE is the true
  169.              solution corresponding to X(j), FERR(j) is an estimated upper
  170.              bound for the magnitude of the largest element in (X(j) - XTRUE)
  171.              divided by the magnitude of the largest element in X(j).  The
  172.              estimate is as reliable as the estimate for RCOND, and is almost
  173.              always a slight overestimate of the true error.
  174.  
  175.      BERR    (output) REAL array, dimension (NRHS)
  176.              The componentwise relative backward error of each solution vector
  177.              X(j) (i.e., the smallest relative change in any element of A or B
  178.              that makes X(j) an exact solution).
  179.  
  180.      WORK    (workspace/output) COMPLEX array, dimension (LWORK)
  181.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  182.  
  183.      LWORK   (input) INTEGER
  184.              The length of WORK.  LWORK >= 2*N, and for best performance LWORK
  185.              >= N*NB, where NB is the optimal blocksize for CSYTRF.
  186.  
  187.      RWORK   (workspace) REAL array, dimension (N)
  188.  
  189.      INFO    (output) INTEGER
  190.              = 0: successful exit
  191.              < 0: if INFO = -i, the i-th argument had an illegal value
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CCCCSSSSYYYYSSSSVVVVXXXX((((3333FFFF))))                                                          CCCCSSSSYYYYSSSSVVVVXXXX((((3333FFFF))))
  203.  
  204.  
  205.  
  206.              > 0: if INFO = i, and i is
  207.              <= N: D(i,i) is exactly zero.  The factorization has been
  208.              completed, but the block diagonal matrix D is exactly singular,
  209.              so the solution and error bounds could not be computed.  = N+1:
  210.              the block diagonal matrix D is nonsingular, but RCOND is less
  211.              than machine precision.  The factorization has been completed,
  212.              but the matrix is singular to working precision, so the solution
  213.              and error bounds have not been computed.
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.